MCP

BindAI provides a lightweight HTTP-based MCP integration package for discovering and invoking external tools. The current implementation is intentionally small and focused on connecting BindAI’s tool system to an HTTP service that exposes a simple tool-discovery and tool-invocation interface. It should be understood as a lightweight HTTP bridge, not as a complete implementation of the Model Context Protocol.

Current MCP Scope

The bindai-mcp package currently provides:

MCPClient
MCPTool
HTTP-based tool discovery
HTTP-based tool invocation
Tool metadata and schema mapping
Integration with the BindAI tool abstraction

The current implementation does not attempt to implement the complete MCP protocol. The package provides a practical integration boundary for external tools while keeping the external HTTP communication behind the BindAI tool abstraction.

MCP Package

The package is:

bindai-mcp

Its public API currently exposes:

from bindai_mcp import MCPClient, MCPTool

The package currently depends on:

httpx
bindai-tool

The package itself declares:

Python >= 3.11

Architecture

The current implementation can be understood as:

BindAI Agent
      |
      v
BindAI Tool System
      |
      v
MCPTool
      |
      v
MCPClient
      |
      | HTTP
      v
External HTTP Tool Service

The external service exposes tools through a small HTTP interface. MCPClient discovers those tools and creates MCPTool instances that can participate in the BindAI tool system.

MCPClient

MCPClient is the client used to communicate with the external HTTP tool service. Create a client with the service URL:

from bindai_mcp import MCPClient

client = MCPClient("http://localhost:8000")

The client currently stores the configured URL and provides asynchronous tool discovery through:

tools = await client.list_tools()

The client does not currently provide explicit connect() or disconnect() methods. It also does not maintain a persistent MCP session.

Tool Discovery

Tool discovery is performed with:

await client.list_tools()

The current implementation sends:

GET {server_url}/tools

For example:

GET http://localhost:8000/tools

The response is expected to contain a JSON list of tool definitions. A conceptual response is:

[
  {
    "name": "search",
    "description": "Search documents",
    "schema": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string"
        }
      }
    }
  }
]

Each returned item is converted into an MCPTool.

Tool Metadata

An externally discovered tool can provide:

name
description
schema

The schema is optional. If no description is provided, the implementation uses an empty string. If no schema is provided, the implementation uses an empty dictionary. For example:

{
  "name": "search",
  "description": "Search documents",
  "schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string"
      }
    }
  }
}

The resulting BindAI tool exposes the same metadata through its tool definition.

MCPTool

MCPTool is the BindAI Tool implementation created for each discovered external tool. Its public properties include:

tool.name
tool.description
tool.definition

The tool definition contains:

tool name
tool description
parameter schema

For example:

tool.definition

produces a BindAI ToolDefinition containing the discovered metadata. This allows an external HTTP tool to participate in BindAI’s existing tool abstraction.

Tool Invocation

When an MCPTool is executed, the current implementation sends:

POST {server_url}/call

For example:

POST http://localhost:8000/call

The JSON request body has the following structure:

{
  "tool": "search",
  "arguments": {
    "query": "BindAI"
  }
}

The tool field contains the name of the discovered tool. The arguments field contains the arguments supplied by the BindAI execution context.

Tool Arguments

When an MCPTool receives an execution context containing variables, those variables are used as the tool arguments. For example:

context.variables = {
    "query": "BindAI"
}

results in a request equivalent to:

{
  "tool": "search",
  "arguments": {
    "query": "BindAI"
  }
}

If the execution context does not provide variables, the implementation uses an empty argument dictionary. The current MCP implementation does not perform additional argument transformation or validation beyond the behavior provided by the underlying BindAI tool definition and external service.

Tool Results

After invoking the external service, the response body is parsed as JSON. The JSON response is returned through BindAI’s ToolResult:

ToolResult(
    success=True,
    output=response.json(),
)

For example, if the external service returns:

{
  "results": [
    "BindAI documentation"
  ]
}

the BindAI tool result contains that object as its output.

HTTP Errors

The current implementation calls:

response.raise_for_status()

for HTTP requests. Therefore, HTTP error responses result in an exception rather than being converted into a successful ToolResult. Applications should handle these failures at the appropriate application or agent boundary. A conceptual flow is:

BindAI Tool
     |
     v
HTTP Request
     |
     +---- 2xx ---> JSON Tool Result
     |
     +---- HTTP Error ---> Exception

MCP and BindAI Tools

The main purpose of the package is to bridge external HTTP tools into the BindAI tool system. The relationship is:

                  BindAI Tool System
                         |
              +----------+----------+
              |                     |
              v                     v
        Local Python Tool       MCPTool
              |                     |
              v                     v
        Application Code      External HTTP Service

This allows an application to combine locally implemented tools with tools exposed by an external service. The agent can interact with the resulting tools through BindAI’s normal tool abstraction.

MCP and Agents

An application can expose discovered MCPTool instances to an agent using the normal BindAI tool mechanisms. The conceptual flow is:

MCPClient
    |
    | list_tools()
    v
MCPTool instances
    |
    v
BindAI Tool Registry / Agent
    |
    v
Tool Selection
    |
    v
MCPTool.execute()
    |
    v
External HTTP Service

The agent does not need to implement the external service’s HTTP request format directly. The MCP integration keeps that communication inside the tool implementation.

MCP and Workflows

MCP tools can participate in workflows when they are exposed through BindAI’s normal tool system. For example:

Workflow
    |
    v
Agent
    |
    v
MCPTool
    |
    v
External HTTP Service

The workflow remains responsible for orchestration. The MCP package provides the external tool boundary. Features such as conditions, loops, parallel execution, retries, timeouts, and human tasks belong to the corresponding BindAI workflow or automation systems rather than to bindai-mcp itself.

MCP and Automation

The bindai-mcp package does not currently provide its own automation or event-trigger integration. MCP tools may still be used by applications that also use BindAI automation and event infrastructure, provided the tools are registered through the normal BindAI mechanisms. For example:

Automation
    |
    v
BindAI Application
    |
    v
Agent / Tool Execution
    |
    v
MCPTool
    |
    v
External HTTP Service

The automation layer and MCP layer remain separate responsibilities.

Observability

The bindai-mcp package does not currently provide a dedicated MCP observability system. It also does not itself expose MCP-specific event types or an MCP event recorder. Applications can still observe MCP-backed tool execution through whatever logging, instrumentation, or execution observability they apply around the BindAI tool and agent layers. BindAI’s broader runtime observability facilities can therefore be used at the application level without implying that the MCP package itself implements tracing or monitoring.

Configuration

The current MCPClient requires only a URL:

client = MCPClient("http://localhost:8000")

The package does not define a dedicated MCP configuration file format. It also does not define built-in environment variables such as:

MCP_SERVER_URL
MCP_API_KEY

Applications are free to obtain the URL and any required credentials from their own configuration system. For example:

import os

from bindai_mcp import MCPClient

client = MCPClient(
    os.environ["MCP_SERVER_URL"]
)

The exact configuration mechanism is an application concern.

Authentication

The current MCPClient implementation does not provide a built-in authentication mechanism. In particular, the current client does not expose configuration for:

API keys
Bearer tokens
OAuth
client certificates
custom authentication headers

If the external service requires authentication, the application must provide an appropriate integration mechanism or extend the client implementation. Do not assume that an MCP service is authenticated simply because it is reachable over HTTP.

Security

MCP-backed tools can provide access to external systems and should therefore be treated as security-sensitive application components. Applications should consider:

Authentication
Authorization
TLS
Network restrictions
Input validation
External service permissions
Tool permissions
Secret management
Logging of sensitive information

The current bindai-mcp client does not implement these concerns itself. Do not expose sensitive external operations to agents unless the application intentionally allows them.

Tool Permissions

External services may expose tools that perform different levels of access. For example:

External Service
    |
    +---- Read Data
    |
    +---- Search Data
    |
    +---- Update Data
    |
    +---- Delete Data

Applications should decide which discovered tools are appropriate for each agent. Avoid automatically exposing sensitive or destructive operations to every agent. Use the principle of least privilege when deciding which external tools an agent can invoke.

Timeouts and Reliability

The current MCPClient does not expose a configurable timeout parameter. The underlying HTTP behavior is provided by httpx. Applications that require strict timeout, retry, circuit-breaker, or resilience policies should account for this at the application or integration layer. External HTTP services can fail because of:

Network problems
Service outages
Invalid requests
Authentication failures
HTTP errors
Unexpected responses
Latency or timeout conditions

Treat MCP-backed tools as external dependencies.

Testing

The bindai-mcp package includes tests for its core behavior. The current test coverage verifies:

Tool discovery
Tool metadata
Tool schema mapping
BindAI ToolDefinition generation
Tool invocation
Tool argument forwarding
Tool result handling

The discovery test verifies that a response from:

GET /tools

is converted into MCPTool instances. The invocation test verifies that:

POST /call

receives the expected tool name and arguments. A representative test boundary is:

Test
 |
 v
MCPClient / MCPTool
 |
 v
Mock HTTP Client
 |
 v
Expected Tool Metadata / Result

The current tests mock the HTTP layer rather than contacting a production MCP service.

Example Test Contract

A discovered tool can look like:

{
  "name": "search",
  "description": "Search documents",
  "schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string"
      }
    }
  }
}

The resulting tool should expose:

tool.name
# "search"

tool.description
# "Search documents"

tool.schema
# {
#     "type": "object",
#     "properties": {
#         "query": {"type": "string"}
#     }
# }

When executed with:

context.variables = {
    "query": "BindAI"
}

the external service should receive:

{
  "tool": "search",
  "arguments": {
    "query": "BindAI"
  }
}

HTTP Bridge Contract

The current bridge has two core endpoints.

Tool discovery

GET /tools

Expected response:

[
  {
    "name": "tool-name",
    "description": "Tool description",
    "schema": {}
  }
]

Tool invocation

POST /call

Expected request:

{
  "tool": "tool-name",
  "arguments": {}
}

Expected response:

{
  "result": "..."
}

The exact response payload is not transformed into a special MCP response structure. The JSON returned by the external service becomes the output of the BindAI ToolResult.

Example Usage

A minimal application can discover external tools with:

import asyncio

from bindai_mcp import MCPClient

async def main():
    client = MCPClient("http://localhost:8000")

    tools = await client.list_tools()

    for tool in tools:
        print(tool.name)
        print(tool.description)
        print(tool.definition)

asyncio.run(main())

The discovered tools can then be integrated with the application’s normal BindAI tool configuration.

Docker

The MCP package itself does not start an HTTP server. It is a client-side integration package that communicates with an already-running HTTP service. When BindAI runs inside Docker, the configured MCP service must be reachable from the container. For example:

BindAI Container
       |
       | HTTP
       v
MCP HTTP Service

If the external service runs in another Docker container, the containers must be able to communicate over the appropriate Docker network. If the service is external, the BindAI container needs appropriate outbound network access.

Docker Compose

A Docker Compose deployment can include a BindAI application and an external HTTP tool service:

Docker Compose

+--------------------+
| BindAI Application |
|                    |
| Agent              |
| Workflow           |
| MCPClient          |
+---------+----------+
          |
          | HTTP
          v
+--------------------+
| HTTP Tool Service  |
|                    |
| External Tools     |
+--------------------+

The exact service configuration depends on the external HTTP tool provider. The bindai-mcp package itself does not provide a server container or Compose service.

Current Limitations

The current implementation is intentionally lightweight. It should not be described as a complete MCP protocol implementation. The current package does not implement a complete MCP stack including features such as:

Full protocol negotiation
MCP session management
MCP resources
MCP prompts
Multiple MCP transport implementations
Standard MCP server implementation
Built-in authentication
OAuth flows
MCP-specific tracing
Full protocol compliance across MCP features

The current implementation is specifically centered on:

GET  /tools
POST /call

and the conversion of discovered external tools into BindAI Tool objects.

MCP vs BindAI Connections

MCP and BindAI Connections provide different integration approaches.

Capability	`bindai-mcp`	BindAI Connections
External tools	Yes	Depends on integration
Tool discovery	Yes	Depends on integration
HTTP communication	Yes	Many integrations
Generic external tool boundary	Yes	No
Dedicated service integration	No	Yes
BindAI tool integration	Yes	Depends on integration
Protocol implementation	Lightweight HTTP bridge	BindAI-specific
Service-specific operations	No	Primary purpose

Use a BindAI Connection when BindAI provides a dedicated integration for the service. Use bindai-mcp when the required capability is exposed through the compatible HTTP tool bridge.

MCP vs Local Tools

Local tools execute application-defined Python code. MCP tools represented by MCPTool forward execution to an external HTTP service. Local tool:

Agent
  |
  v
BindAI Tool
  |
  v
Python Function

MCP-backed tool:

Agent
  |
  v
BindAI Tool
  |
  v
MCPTool
  |
  v
HTTP Service

Both can participate in the BindAI tool system. The primary difference is where the actual operation executes.

Recommended Project Structure

An application using the MCP bridge may keep MCP-related setup separate from agents and workflows:

my-ai-app/

├── agents/
├── tools/
├── workflows/
├── mcp/
│   └── clients.py
├── tests/
│   └── test_mcp.py
├── bindai.toml
├── main.py
└── .env

The exact project structure is application-specific. The important principle is to keep external-service configuration and credentials separate from agent business logic.

Production Considerations

When deploying an application that uses the MCP bridge, consider:

External service availability
Network connectivity
Authentication requirements
TLS
Tool permissions
Input validation
HTTP failures
Timeouts
Retry policies
Rate limits
External service monitoring
Secret management

The current MCP package is intentionally minimal, so production applications may need additional infrastructure around it. A production application should define what happens when an external tool service becomes unavailable.

Future MCP Capabilities

The MCP integration can be expanded in future releases. Potential areas include:

More complete MCP protocol support
Standard MCP transports
MCP resources
MCP prompts
Session management
Authentication support
Richer tool metadata
Improved protocol compatibility
MCP server functionality
More advanced error and timeout handling
Deeper observability integration

These capabilities should be introduced incrementally while preserving the existing BindAI tool abstraction where practical.

Best Practices

Treat external MCP-backed services as external dependencies.
Keep MCP configuration separate from agent business logic.
Never hard-code credentials.
Use secure configuration and secret storage.
Expose only the tools an agent actually needs.
Follow least-privilege principles.
Validate external tool inputs.
Handle HTTP failures explicitly.
Use appropriate timeout and retry strategies at the application level.
Test MCP integrations independently.
Do not assume authentication is provided by bindai-mcp.
Do not assume MCP resources or prompts are supported.
Do not assume session management is available.
Do not describe the v0.1 implementation as full MCP protocol compliance.
Verify the capabilities of the external HTTP service before depending on them.

Summary

BindAI v0.1 provides a lightweight HTTP-based MCP integration through the bindai-mcp package. The main flow is:

BindAI Agent
      |
      v
BindAI Tool System
      |
      v
MCPTool
      |
      v
MCPClient
      |
      | HTTP
      +---- GET /tools
      |
      +---- POST /call
      |
      v
External HTTP Tool Service

The current implementation provides:

MCPClient
MCPTool
HTTP tool discovery
HTTP tool invocation
Tool metadata and schema mapping
BindAI Tool integration
JSON tool results

The current implementation is intentionally smaller than a complete MCP protocol stack. For v0.1, the MCP layer should therefore be viewed as a practical HTTP tool bridge and foundation for future MCP capabilities, rather than as a full MCP implementation. Applications that require specific MCP protocol features should verify that those features are supported before depending on them.

​MCP

​Current MCP Scope

​MCP Package

​Architecture

​MCPClient

​Tool Discovery

​Tool Metadata

​MCPTool

​Tool Invocation

​Tool Arguments

​Tool Results

​HTTP Errors

​MCP and BindAI Tools

​MCP and Agents

​MCP and Workflows

​MCP and Automation

​Observability

​Configuration

​Authentication

​Security

​Tool Permissions

​Timeouts and Reliability

​Testing

​Example Test Contract

​HTTP Bridge Contract

​Tool discovery

​Tool invocation

​Example Usage

​Docker

​Docker Compose

​Current Limitations

​MCP vs BindAI Connections

​MCP vs Local Tools

​Recommended Project Structure

​Production Considerations

​Future MCP Capabilities

​Best Practices

​Summary

MCP

Current MCP Scope

MCP Package

Architecture

MCPClient

Tool Discovery

Tool Metadata

MCPTool

Tool Invocation

Tool Arguments

Tool Results

HTTP Errors

MCP and BindAI Tools

MCP and Agents

MCP and Workflows

MCP and Automation

Observability

Configuration

Authentication

Security

Tool Permissions

Timeouts and Reliability

Testing

Example Test Contract

HTTP Bridge Contract

Tool discovery

Tool invocation

Example Usage

Docker

Docker Compose

Current Limitations

MCP vs BindAI Connections

MCP vs Local Tools

Recommended Project Structure

Production Considerations

Future MCP Capabilities

Best Practices

Summary